{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sisl\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First TranSiesta example.\n",
    "\n",
    "This example will *only* create the structures for input into TranSiesta. I.e. `sisl`'s capabilities of creating geometries with different species is a core functionality which is handy for creating geometries for Siesta/TranSiesta.\n",
    "\n",
    "This example will teach you one of the *most important* aspects of performing a successful DFT+NEGF calculation. Namely, that the electrodes should *only* couple to its nearest neighbouring cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "graphene = sisl.geom.graphene(1.44, orthogonal=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "graphene.write('STRUCT_ELEC_SMALL.fdf')\n",
    "graphene.write('STRUCT_ELEC_SMALL.xyz')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elec = graphene.tile(2, axis=0)\n",
    "elec.write('STRUCT_ELEC.fdf')\n",
    "elec.write('STRUCT_ELEC.xyz')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above two code blocks writes two different electrodes that we will test in TranSiesta. In this example, we will have the transport direction along the 1st lattice vector (0th index in Python). Note how TranSiesta does not limit your choice of orientation. *Any* direction may be used as a semi-infinite direction, just as in TBtrans."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "device = elec.tile(3, axis=0)\n",
    "device.write('STRUCT_DEVICE.fdf')\n",
    "device.write('STRUCT_DEVICE.xyz')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercises\n",
    "\n",
    "As this is your first example of running TranSiesta there are a few things you should know:\n",
    "\n",
    "1. *Any* TranSiesta calculation starts by calculating the electrode Hamiltonians and their densities.\n",
    "  - Start by defining your electrode and figure out how *long* it should be (by the end of this example you should know how)\n",
    "  - Converge $k$-points and parameters such that the electrode truly reflects your physical boundaries for the bulk electrode.\n",
    "  - As in [TB 5](../TB_05/run.ipynb) you should *always* use periodicity if allowed. Using Bloch's theorem will greatly increase throughput with little effort.\n",
    "  - Run the electrode with `siesta` executable as this `siesta --electrode`. This will create the `*.TSHS` file, which is the basic ingredient used in TranSiesta/TBtrans to calculate the self-energies from the given electrode.\n",
    "  - Additionally, you can read the electrode Hamiltonian (from the `*.TSHS`) into sisl and create band-structures, just as in [TB 1](../TB_01/run.ipynb).\n",
    "2. Define your device structure by ensuring the electrode length as determined in step 1. \n",
    "  - Add a few *screening layers* to ensure a smooth potential towards the bulk electrodes, do this for all electrodes.\n",
    "  \n",
    "    (*general advice, you don't need to do it in this example*)\n",
    "  - Add the scattering part which connects the electrodes.\n",
    "3. Define the input for TranSiesta, you can with benefit use the bash-script `tselecs.sh` which will generate a default input for $N\\ge1$ electrodes and only require slight changes.\n",
    "\n",
    "   (*general advice: you don't need to do it for this exercise*)\n",
    "4. Run TranSiesta\n",
    "  - Go through the output of TranSiesta to assert that it has run without errors (always do this!) (always, **always** do THIS!)\n",
    "  - Ensure the SCF has indeed converged, TranSiesta should not stop because of the maximum allowed iterations is too small. Optionally, you may use this flag `SCF.MustConverge T` (the default) to make TranSiesta die if it does not converge.\n",
    "  - Ensure that the `dQ` column is close to $0$, below $0.01$ is preferable. Further, it is advised that the last couple of iterations also obey this condition.\n",
    "  - Go through the lines after:\n",
    "  \n",
    "        ```\n",
    "        ***************************\n",
    "        *  WELCOME TO TRANSIESTA  *\n",
    "        ***************************\n",
    "        ```\n",
    "        \n",
    "    which is the point where TranSiesta starts.  \n",
    "    Try and familiarize your-self with the output of TranSiesta, lots of information is printed. Some more important than others.\n",
    "    \n",
    "5. Run TBtrans. Notice that TBtrans will default to the values given to TranSiesta, so do not be worried about missing `TBT.*` flags in the input files. However, remark that TBtrans will *only* use the `TS.<>` flag if `TBT.<>` does not exist.\n",
    "\n",
    "### For this example follow these steps:\n",
    "\n",
    "- Run TranSiesta for the electrode:\n",
    "\n",
    "       siesta --electrode RUN_ELEC.fdf > RUN_ELEC.out\n",
    "       \n",
    "- Run TranSiesta for the device region:\n",
    "\n",
    "       siesta RUN.fdf > RUN.out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This finalizes your (possibly) first TranSiesta calculation. All should have gone fine here, after some time.\n",
    "You should also have noticed that TranSiesta is considerably slower than TBtrans. \n",
    "\n",
    "- Continue by deleting all `ELEC.*` files\n",
    "- Edit `RUN_ELEC.fdf` to include the `STRUCT_ELEC_SMALL.fdf` instead of `STRUCT_ELEC.fdf`\n",
    "- Re-run the electrode calculation (`siesta --electrode RUN_ELEC.fdf > ELEC_SMALL.out`)\n",
    "- Re-run TranSiesta (`siesta RUN.fdf > TS_SMALL.out`)\n",
    "- What happens? And more importantly, why?!?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Evidently TranSiesta does not allow too small electrodes as that would create an erroneous coupling along the semi-infinite directions. Luckily, this may easily be inferred in the electrode output by looking for this keyword: `Internal auxiliary supercell`. The output of TranSiesta will print 3 numbers $\\langle A\\rangle \\mathrm{x} \\langle B\\rangle \\mathrm{x}\\langle C\\rangle$ which corresponds to the number of neighbouring unit-cells the primary unit-cell connects to. The important number to look for is the number corresponding to the semi-infinite direction.  \n",
    "What should this number be in order to preserve nearest-neighbour unit-cell interactions **only**? Say, if the semi-infinite electrode sits along the $\\langle A\\rangle$ direction, what should the number $\\langle A\\rangle$ (always!) be?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
